Cream of the Crop 1

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / TPP112.ARJ / TPP.DOC < prev next >

Wrap

Text File | 1992-04-18 | 19KB | 445 lines

---------------------------------------------------------------------- 04/18/92 Turbo Pascal Pre-Processor All Rights Reserved Copyright (c) 1991-1992 by SupremeSoft Version 1.12 ---------------------------------------------------------------------- Introduction ------------ What is TPP? TPP is a pre-processor designed to work with Turbo Pascal. Many programmer's who are both C and Pascal programmers find that they miss C's pre-processing capabilities. In addition, professional Pascal programmers find it quite absurd to declare constants for such mundane things as maximum values for array indexes. This adds to the programs code size, as well as wasting precious memory. Why declare a constant when you'll only be using it as a fixed value, which the compiler can determine at compile-time as it is? In C, all you need to do is use the pre-processor to define this value. (The question of why use constants at all comes up. Especially if they are useful, but wasteful of resources. Most languages use constants, whereas C and C++ provide macro equivalents, and thus have no constant keywords) Finally, Turbo Pascal has a gotcha for all constants. They sit in your data segment. Turbo Pascal, though smart in some ways, is not smart enough to know that this constant is only a "hard coded" value, and will thus not replace all references for that constant with its definition. Besides this, there is a big caveat for using constants as initializers. Reading your Turbo Pascal manual carefully, you will see that any constant is only initialized ONCE. Even if it is declared in a procedure, it is only initialized ONCE, and lives in the data segment and NOT the procedures local call stack! In comes TPP. TPP will take your simple constants and replace all occurrences of that constant with its definition. Besides that, TPP can be used to abbreviate coding declarations which will later be expanded at compile time. ----------------- How to use TPP ----------------- TPP was designed to allow you to use the same source code that you would normally use, but also allow you to use TPP keywords. In addition, TPP works exactly like the Turbo Pascal Compiler. It will not recompile units that do not need to be. (Although, it is not as smart as the Turbo compiler as you will see later) TPP scans your source, looking for a {#DEFINE} statement. This is the signal to TPP that a macro definition is about to start. After this comes the regular constant definition. For example: Normal source: Const UpperLimit = 3; {This is the upper limit} LowerLimit = -1; {This is the lower limit} To adapt to TPP: Const {#DEFINE} UpperLimit = 3; {This is the upper limit} {#DEFINE} LowerLimit = -1; {This is the lower limit} Using this {#DEFINE} statement, your source will compile under Turbo as usual, but can also be compiled using TPP. You do not need to keep two different sets of source code. That is all there is to it. Now, every occurrence of UpperLimit will be replaced by a "3". You can also define string constants etc. In short any constant that will work for the Turbo compiler will work for TPP. Initialized constants, will *NOT* work in TPP, and should be avoided during regular use of the Turbo compiler. Initialized constants have numerous flaws and many, many gotchas. (Contact us for more detailed information on why not to use initialized constants) For example, the following is *NOT* legal for TPP: Const {#Define} LowerLimit : Byte = -1; {This is the lower limit} You may use TPP to ease your coding a bit, by using the TPP macro feature as you would normal text macros. For instance: {#DEFINE} DOS = Intr(21h); Then, in your code, you may say: DOS; {Call DOS} and TPP will change this to : Intr(21h); {Call DOS} Note that TPP can thus be used for other things than just constants! {#DEFINE} statements may be used anywhere in your source code. And of course, TPP is not case sensitive. ------------- Limitations ------------- TPP is not like the C macro pre-processor. You may not pass variables in or out, nor do arithmetic expressions. For example, the following are accepted, but are probably not what you want the macro to do: 1. {#DEFINE} TWICE(X) = X*X; 2. {#DEFINE} HIGH(X) = Odd(X) < Even (X); 3. {#DEFINE} Limits = 32 * MaxValue; For definition 1, you would need to have a statement of: TWICE(Z); Expansion then becomes: X*X; You probably want: Z*Z; For definition 2, you would need to have a statement of: HIGH(Z); Expansion then becomes: Odd(X) < Even(X); You probably want: Odd(Z) < Even(Z); For definition 3, you would need to have a statement of: Limits; Expansion then becomes: 32 * MaxValue; Note: This is not evaluated at macro definition time, unlike in C. However, Turbo will usually evaluate it at compile-time, so this is actually a GOOD use for TPP. You must be careful not to have the macro name anywhere else in your source code, or else it will get expanded. (That is rather obvious) If you use the Const feature of TPP, be careful of the following: Const {#DEFINE} UpperLimit = 3; {This is the upper limit} {#DEFINE} LowerLimit = -1; {This is the lower limit} Type . . When TPP processes your file, everything but the comments will be stripped out, leaving: Const {This is the upper limit} {This is the lower limit} Type . . The Turbo compiler, will *NOT* accept this. There must be something following the CONST declaration. Be aware of this problem. The only real work around is to comment out the CONST statement. (This may changed in later versions of TPP) ------------- How TPP works -------------- TPP will scan your source file looking for {#DEFINE} statements or macro names. It handles Units just like the Turbo compiler, and looks for a USES keyword. If it finds one, it suspends processing of the current file and looks at the last file in the USES list. (Just as the Turbo compiler does) If the TPU for that file is older than the file, TPP will process that file. This is done for all Units in the USES list. You may define a macro in one unit, and use it in another, as long as that unit is listed in the second file's USES list. Confused? Follow the same programming style as you do regularly. TPP needs no change in programming! It will allow you to treat your source the same way as Turbo does. Consider the following: Unit 1; ... {Not the next line can be in either the interface OR the implementation section. Either way it will be visible to other units using this unit} {#DEFINE} Upper = 99; Unit 2; Uses Unit 1; ... Var t : array[1..Upper] of real; Even though Unit2 doesn't declare Upper, it can still use it. ------------------------------------------------------------------ One major flaw in TPP: If Unit1 does NOT need re-compiling, then the macro Upper will never get defined for TPP! ------------------------------------------------------------------- Once TPP encounters a macro, it stores the macro name, and its corresponding definition. In all later files, any time the macro name is detected, it will get replaced with the definition. Once TPP reads the macro, it will remove it from the source file. Thus causing the Turbo compiler to "ignore" the macro, since it isn't there. TPP will scan all the files needed, but will only produce a new file if any changes are made to the original source. Depending on the mode of operation, this new file will either overwrite the original source file, be named DUM?.PAS or will be erased once the program terminates. Once TPP completes pre-processing the main file and all of its corresponding units, it will invoke the Turbo Pascal compiler. Turbo will then work with the TPP processed files and any others it needs. TPP will report on the number of lines it has processed, and the time it took to complete the processing. You should find that TPP blazes through your files, and only slows once it encounters a macro definition, or a macro expansion. ---------- Specifics ---------- Calling Syntax: TPP filename[.PAS] [/O | /N | /E] [Turbo Options] Where: /O Indicates overwrite source files /N Indicates no compile after processing /E Indicates execute an editor BEFORE Turbo compiles Turbo Options are any Turbo Pascal options you wish to use and they are passed directly on to the compiler. You may opt to leave off the PAS extension, TPP will add it. The filename *MUST* be in the current directory, otherwise the program will abort immediately. (Other files may be anywhere) More: If you are compling the program, TPP will need to create a temporary directory to store the TPP processed files. It is called TPPT, and exists off the current directory. If you use the /E option then TPP will invoke either the editor specified in the EDITOR environment variable, or a default editor of Q.EXE (The Qedit editor) BEFORE it calls the Turbo compiler. The editor is passed a command line of: *.PAS, and thus you may edit all of the TPP processed files. Note that only the TPP processed files will be available in the TPPT directory. If a file does not get changed by TPP, there is no need to make a new copy of it. Why would you want to call an editor? Well, if you know that a file will have illegal syntax after being processed by TPP, you can go an correct these errors. Tpyically, once TPP has stripped a file of all constants, you are left with a CONST keyword, but no definitions. Turbo doesn't like this, and executing the editor before compiling allows you to remove all the CONST keywords. Once compilation completes, all TPU and EXE files will be moved to the original directory. If the /O option is specified, then all PAS files will be moved back as well. If you are not compiling, and have not specified the /O option, then you will be left with some DUM?.PAS files, where ? indicates an integer value. These are the TPP processed files. If you specify the /O option, then the original source files will be renamed to BAK files, and the TPP processed will be named to the original source files. When the Turbo compiler is invoked, TPP will attempt to swap out to disk or EMS. If successful, only 1.5K of TPP will be left in memory. If it cannot swap out, it attempts to free up as much memory as it can. This allows TPC to have as much memory available as possible. When invoked, TPC will be passed the following: TPC /M filename [Turbo Options] Note that it will always be invoked using the /M option! Returns: The DOS ERRORLEVEL return code will be set as follows: 1 Help screen invoked 2 File error occurred 3 Out of memory error 4 File not in current directory This may be useful in batch files, or in a MAKE utility. ------------------------- How does TPP find files? -------------------------- TPP will attempt to find and read TPC.CFG in order to find out where all your source files are located. If it cannot find the source file in the current directory, it will then scan the Unit directories listed in TPC.CFG. It will *NOT* look on your PATH! ReadOnly files are valid, and will be processed correctly. ------------------------ Errors and Memory issues ------------------------ How much memory does TPP use? That depends on how many macros you define, how many unit dependencies you have, and the size of your source. Typically, TPP can process up to 50,000 lines in as little as 100K, with 300 macros defined. Upon a memory error, TPP will give you a standard "Out of memory" error. If this happens, you will have to remove some TSR's to make room. But be aware of this, if TPP cannot complete, there is no way TPC will ever be able to compile, since it too will usually run out of memory. Upon a file error, TPP will issue a message, asking you to either abort or continue. If you abort, you will be asked to confirm it. Then an error code will be output, which is the standard IORESULT that any Turbo program issues. Look it up in the programmers reference manual. If it is a file error, you've got a problem. If it's some other error caused by TPP, *please let us know*! ---------- Warnings ---------- Under no circumstances have the word USES anywhere before your actual USES statement. TPP is not a compiler, and will treat a USES within a comment block to be the keyword it wants. Any time after the original USES statement, TPP will ignore the word. Thus, this should NOT happen: Unit Test; {This unit uses two dependencies} Interface Uses DOS,CRT; But, this is legal: Unit Test; {This is a test unit} Interface Uses DOS,CRT; {This unit uses two dependencies} When TPP is run in compilation mode, it needs to create the directory TPPT. IF this already exists, you are asked if you wish to use it or not. If you answer yes, be aware that if any files already exist in this directory, TPP will *NOT* overwrite them with new copies. Why? Usually, the copies in those directories are identical to the ones about to overwrite them. Thus, to save time, TPP reports an error, but does not abort operation. The question comes up, when do I use TPP? Do I develop with it? The answer is no. Since TPP lets you use the same source code, develop, test and debug using your normal methods. But when it comes time to do a production version, run TPP. Of course, if you are using the macro expansion capabilities, then you must use TPP all the time. TPP is not memory resident, and does not interface with the Turbo compiler. Therefore, you must use the command line compiler. (And no, there are no plans to develop a sophisticated TSR version...) TPP is very fast. It doesn't need to do all that much, but it is a good idea to have a nice sized disk cache in place, since a lot of disk activity will be apparent. Besides, the Turbo compiler will also be given a boost. ----------------- Savings using TPP ----------------- How much do you *really* save using TPP? Honestly, that depends on how many CONSTANTs you have in any program. If you program correctly, there should be very few, and thus the code size savings are minimal and probably not worth it unless you are having a code size contest. Code size is hardly affected because now you are substituting a memory location for a hard coded value, but the instruction is still coded. Thus, the only savings comes from TPP's constant folding and other optimizations. So code size is not a major factor. But memory size is! By using TPP you save the memory space needed for all those constants that are being held in memory by Turbo Pascal. The more you have, the more you save. This should become apparent immediately. By using the enhanced macro expansion capability of the program, you might save some code and memory space, but not much. However you save on coding time, another important development factor. ----------------------------------------------------------------- Warranty and License: ----------------------------------------------------------------- There is NO warranty either expressed or implied. SupremeSoft can not be held accountable for anything resulting from the use, or misuse, of this program. Your use of this program acknowledges the fact that you understand that you are using this program of your own free will, and will take any consequences resulting from that action and cannot hole SupremeSoft responsible for any reason. You are granted a limited license of 30 days to evaluate this program. Should you use it beyond that period, you must register your copy, or else be in violation of this license agreement. To register, send $15.00 to the address below: Send a check/money order to the following address: SupremeSoft 105 Deerfield Drive Easton, CT 06612 Re: TPP (1.12) You may also contact: msingh@ucs.indiana.edu if you have access to the Internet. You can report bugs, problems, pains, antecdotes, etc. ---------------------- Registration benefits ---------------------- TPP will annoy Shareware users. There is an opening random delay, up to 9 seconds, and there is another delay at the end of the program, before you are returned to DOS. (But not before TPC is executed) Why? It has been our experience that the Shareware concept doesn't work as well if one offers no limitations on the program. Thus, rather than leaving out features, annoyances are introduced. A lot of time has gone into the development of this program, and we feel that users should pay for the program if it is of any use to them. Registered users have no delay's, or requests for key presses. In addition, at the time of registration we will send you the absolute latest version of the program. After receipt of the program, you may send us a SASE disk mailer and receive the next update for free, for the life time of the program's development. That's right, for free, as long as you pay for postage and provide a mailer.